Release 10.1A: OpenEdge Development:
Programming Interfaces

Managing audit event context

OpenEdge provides an architecture for adding context to the audit event records in an audit trail. Without audit event context, an audit trail contains a stream of events that have little apparent relationship to one another. Using various audit contexts, you can group audit events together in various combinations. Then, when you want to generate auditing reports, you can report on audit events based on the context or contexts in which they are recorded.

OpenEdge can organize auditing events within the following different event context areas:

Database transactions
Client login sessions
Application context
Application event groups

You can explicitly control all of these event contexts, except the database transaction context. OpenEdge always generates database transaction context information (transaction ID and sequence values) that is recorded with each auditing event generated during a database transaction. Otherwise, you can generate context information for the remaining context areas that also appears in audit event records using the 4GL elements described in this section.

Otherwise, the OpenEdge auditing context architecture allows you to nest these context areas in different ways to organize the auditing events generated by your application. For more information on this auditing context architecture, see OpenEdge Getting Started: Core Business Services . The following sections describe how to generate context information for client login sessions, application context, and application event groups.

Generating client login session context

Client login session context information consists of a client session ID that is recorded for each audit event generated during a client login session. Optionally, it also includes a record keyed by this client session ID that describes the authentication information for the client login session. OpenEdge supports two types of authentication systems for authenticating a user:

The database _User table internal to the OpenEdge RDBMS.
A 4GL application-managed (external) authentication system that can optionally have a corresponding authentication domain defined for it in a trusted domain registry, either configured in an OpenEdge RDBMS or built at run time by the application itself. While not required to log in a client login session, this trusted domain registry is used to set user identities using the SET-CLIENT( ) method or the SET-DB-CLIENT built-in function.

OpenEdge allows you to use both types of authentication system to authenticate a user ID (auditing ID) that is recorded with all audit event records generated for the specified user ID, and which can also be used to indicate the application user ID at the time the event is recorded. For more information on how to specify a user identity as the auditing identity, see the "Setting up application security for auditing" section.

To maintain an auditing context for a client login session, you must do the following:

In your application 4GL, authenticate the user ID that you configure as the auditing ID to an external authentication system, and assert and validate that user ID against the appropriate trusted domain registry using an initialized and sealed client-principal object. For more information, see the "Setting up application security for auditing" section.
If you want additional information about the client login session recorded for the auditing context, in the Data Administration tool or Data Dictionary (character mode only), select the Record Authenticated Client Sessions option in the Database Options dialog box. For more information, see the Data Administration online help or OpenEdge Development: Basic Database Tools . Setting this option allows a client login session record (_client-session) to be written to the database that describes information about the authentication domain for the user ID represented by the client-principal object, various session security values (such as the database unique identifier), and additional detail from selected client-principal object attributes. When auditing is also enabled, this record becomes part of the auditing context.

The initiation and management of the client login session context is primarily the responsibility of methods on the client-principal object, which log in and manage a client login session. Without a client-principal object (using the SETUSERID function or User ID (-U)/Password (-P) parameters), OpenEdge records the configured auditing ID in all related audit event records, but creates no auditing client login session (client login session for the auditing ID). However, when you use a client-principal object to manage an auditing client login session, OpenEdge generates audit events to track the session, such as login, logout, and even the failure to log in (if so directed). Logging in with a client-principal object also causes the value of its SESSION-ID attribute to be written to every audit event record related to this auditing client login session. Again, the associated auditing ID (USER-ID attribute on the associated client-principal object) is written to all audit event records while the auditing client login session is active (logged in) and the auditing ID is also set as the client login session user ID.

Note: Each audit enabled database connected to a Progress session can maintain one current database connection ID, which can be set for a client login session established using its client-principal object.

OpenEdge supports several 4GL elements that provide user identity and client session context information for the audit trail. The client-principal object provides most of the client login session context information. Table 3–3 shows 4GL elements, listed in general order of usage, that generate auditing events or otherwise provide information for an auditing client login session context.

Table 3–3: 4GL elements for auditing client login session context

4GL element	Description
SESSION-ID	Client-principal object attribute that specifies the client login session ID used to identify the client login session context in the audit trail. This value also keys any _client-session record created for the login session.
AUDIT-EVENT-CONTEXT	Client-principal object attribute that allows you to provide additional information to the audit event record's _Event-context field, which you can use to later to query audit event records. This value is written to audit event records generated for the AUTHENTICATION-FAILED( ), SEAL( ), and LOGOUT( ) methods.
AUTHENTICATION-FAILED( )	Client-principal object method that generates an audit event for a failed user login.
SEAL( )	Client-principal object method that generates an audit event for a successful user login, and also generates an optional client login session record with additional information.
SET-CLIENT( )	SECURITY-POLICY system handle method that sets the default Progress session ID (which can be the auditing ID) using a client-principal object instance. It also asserts database connect IDs similar to the SET-DB-CLIENT function.
SET-DB-CLIENT	4GL function that asserts a user ID as the database connection ID (which can be the auditing ID) using a client-principal object instance. This function also generates an audit event for asserting the connection ID for a particular database.
LOGOUT( )	Client-principal object method that generates an audit event for user logout. It also logs out the client login session and sets the client-principal's LOGIN-STATE attribute to "LOGOUT" so that it cannot be validated to set a Progress session or database connection ID.

If the option to record authenticated client sessions is set for an audit-enabled database, calling the SEAL( ) method on an associated client-principal object both logs in the auditing client session (generating an audit event record) and writes a _client-session record. In addition, OpenEdge relates every audit event record generated while this client login session user ID is set as the current auditing ID (including the login audit event record) to this _client-session record by the value of the SESSION-ID attribute on the client-principal object.

So, all audit event records generated, while the user ID for a given client login session is set as the current auditing ID, share the same session ID value and user ID value (which is also the configured auditing ID), and they also share these values with any _client-session record (related by the session ID value) that happens to be written for the given auditing client login session context.

For more information and examples of using the 4GL elements in Table 3–3 to maintain client login sessions, see Chapter 2, " Application Security."

Generating application context

Application context allows you to define your own criteria for organizing audit events together. So, for example, you might associate all audit events in the same application context that are generated for an inventory module to help distinguish them from events that are generated for a shipping and receiving module; or you might want to track access to specific windows and controls in a user interface; or you might have a ProDataSet involved in transactions to update multiple databases, and you want to associate the change tracking in that ProDataSet with the appropriate database. Again, you can use the resulting context to structure the reporting of audit events generated in the resulting audit trail.

OpenEdge generates a new application context event record with each call to the SET-APPL-CONTEXT( ) method on the AUDIT-CONTROL system handle. When you want to end the scope of the current application context, call the CLEAR-APPL-CONTEXT( ) method. The syntax for these methods follows:

Syntax

ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT                        (audit-event-ctx [ , event-detail [ , user-data ]])

logical = AUDIT-CONTROL:CLEAR-APPL-CONTEXT( )

The ctx-id is an application context ID that is a UUID returned as a Base64 character value (with pad characters removed). This application context ID is recorded in all audit event records until the context is changed or cancelled. Each invocation of the SET-APPL-CONTEXT( ) method generates a new application context ID that replaces the previous one in all subsequent audit event records. Thus, only one application context can be active at a time and no nesting of application context is possible.

The input parameters to SET-APPL-CONTEXT( ) are all character values that allow you to specify different levels and types of detailed information about the context, as appropriate for the application. The first, required, parameter specifies an alternate index to the audit event record. So, its length is limited to the maximum size of an index value. Thus, you can use this value as a key for reporting purposes.

If you want to stop recording any application context ID values in audit event records, you must invoke the CLEAR-APPL-CONTEXT( ) method. You can test its logical value for a successful invocation. At no time does the 4GL session ever implicitly invoke the CLEAR-APPL-CONTEXT( ) method. Therefore, you must ensure that all code paths (especially error handling code paths) end the application context correctly. You can also begin another application context at any point after clearing the current application context.

If at any point in the 4GL session you need to determine the current application context ID, you can examine the value of the APPL-CONTEXT-ID attribute on the AUDIT-CONTROL system handle. This attribute returns the Unknown value (?) if no application context is currently set.

The following code fragments show use of these methods and attributes:

DEF VAR user-task as CHAR. DEF VAR id as CHAR. ... user-task = “Salary adjustments”. ... id = AUDIT-CONTROL:SET-APPL-CONTEXT                    ("Payroll app", "FICA calculation", user-task). ... AUDIT-CONTROL:CLEAR-APPL-CONTEXT( ). ... IF id <> AUDIT-CONTROL:APPL-CONTEXT-D THEN ...

Generating audit event groups

Audit event groups work in a similar fashion to application context. You can also nest a series of application contexts within an audit event group or nest a series of audit event groups within an application context.

OpenEdge generates a new audit event group record with each call to the BEGIN-EVENT-GROUP( ) method on the AUDIT-CONTROL system handle. When you want to end the scope of the current audit event group, call the END-EVENT-GROUP( ) method.

The syntax for these methods follows:

Syntax

grp-id = AUDIT-CONTROL:BEGIN-EVENT-GROUP                        (audit-event-ctx [ , event-detail [ , user-data ]])

logical = AUDIT-CONTROL:END-EVENT-GROUP( )

The grp-id is an audit event group ID that is a UUID returned as a Base64 character value (with pad characters removed). This audit event group ID is recorded in all audit event records until the event group context is changed or ended. Each invocation of the BEGIN-EVENT-GROUP( ) method generates a new audit event group ID that replaces the previous one in all subsequent audit event records. Thus, only one audit event group can be active at a time and no nesting of audit event groups is possible.

The input parameters to BEGIN-EVENT-GROUP( ) are all character values that allow you to specify different levels and types of detailed information about the audit event group context, as appropriate for the application. The first, required, parameter specifies an alternate index to the audit event record. So, its length is limited to the maximum size of an index value. Thus, you can use this value as a key for reporting purposes.

If you want to stop recording any audit event group ID values in audit event records, you must invoke the END-EVENT-GROUP( ) method. You can test its logical value for a successful invocation. At no time does the 4GL session ever implicitly invoke the END-EVENT-GROUP( ) method. Therefore, you must ensure that all code paths (especially error handling code paths) end the audit event group correctly. You can also begin another audit event group at any point after ending the current audit event group.

If at any point in the 4GL session you need to determine the current audit event group ID, you can examine the value of the EVENT-GROUP-ID attribute on the AUDIT-CONTROL system handle. This attribute returns the Unknown value (?) if no audit event group context is currently active.

The following code fragments show use of these methods and attributes, in this example, creating an audit event group with nested application context:

DEF VAR user-task as CHAR. DEF VAR ctx-id as CHAR. DEF VAR grp-id as CHAR. ... user-task = “Salary adjustments”. ... grp-id = AUDIT-CONTROL:BEGIN-EVENT-GROUP                        ("Payroll app", "tax calculations", user-task). ... ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT                        ("Payroll app", "Federal tax calculation", user-task). ... AUDIT-CONTROL:LOG-AUDIT-EVENT (34122, ctx-data). ... ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT                        ("Payroll app", "FICA calculation", user-task). ... AUDIT-CONTROL:LOG-AUDIT-EVENT (34123, ctx-data). ... AUDIT-CONTROL:CLEAR-APPL-CONTEXT. ... AUDIT-CONTROL:END-EVENT-GROUP. ... IF grp-id <> AUDIT-CONTROL:EVENT-GROUP-D THEN ...

In this example, two application contexts are invoked in sequence for a different series of audit events, and both are nested within the audit event group. You can also invert this nesting, with a single application context nesting a series of audit event groups. The choice depends entirely upon your application design preferences.